# Building the RF Scythe API Server: A Hybrid RF and Network Hypergraph System

In the complex world of signal analysis and network reconnaissance, visualizing the relationships between disparate data points is key to understanding the battlespace. Today, we're diving into the architecture of the **RF Scythe API Server** (`rf_scythe_api_server.py`), a critical component of the NerfEngine that bridges the gap between Radio Frequency (RF) signals and IP network structures using a hypergraph model.

## Introduction

The RF Scythe API Server is a comprehensive Flask-based backend designed to serve as the central nervous system for visualizing and analyzing signal data. Unlike traditional tools that look at either RF spectrum data *or* network topology, RF Scythe treats both as first-class citizens in a unified **Hypergraph**.

By representing both radio transmitters and network hosts as "nodes" in a shared space, the system can identify complex relationships—like a cluster of devices on the same subnet that are also broadcasting overlapping RF signals.

## Key Features

*   **Hybrid Data Model:** Seamlessly stores and visualizes both RF signal nodes and Network host nodes.
*   **Nmap Integration:** Built-in wrapper for `nmap` allows for active network scanning, automatically converting discovered hosts and services into graph nodes and hyperedges.
*   **Real-Time Updates:** Uses **Flask-SocketIO** to push graph updates to connected clients instantly.
*   **Spatial Indexing:** Optional integration with `scipy` and `sklearn` for advanced spatial queries and clustering.
*   **Automated Relationship Discovery:** automatically generates hyperedges based on shared properties like Service types (e.g., all devices running SSH) or Subnets.

## Technical Deep Dive

### 1. The RF Hypergraph Store

At the heart of the server is the `RFHypergraphStore` class. This in-memory database manages the lifecycle of the graph session.

*   **Nodes:** Can represent an RF emitter (with properties like Frequency, Power, Modulation) or a Network Host (IP, Hostname, Open Ports).
*   **Hyperedges:** connect multiple nodes together. Unlike standard graph edges that connect just two points, a **hyperedge** can connect *N* nodes. This is powerful for representing concepts like "Coherence" between multiple signals or a "Subnet" containing dozens of hosts.

### 2. Bridging Physical and Digital Worlds

One of the most innovative features of the API server is how it handles network data physically. When an IP address is added via the `add_network_host` method, the server assigns it a **pseudo-position**.
*   IP addresses are mapped to lat/lon coordinates algorithmically.
*   This allows network topology to be visualized on the same 3D globe or map context as physical RF emitters, providing a "Cyber-Physical" view of the environment.

### 3. Automated Inference

The server doesn't just store data; it actively looks for patterns.
*   **Service Groups:** The `create_service_hyperedges` method scans all known hosts. If multiple hosts are running the same service (e.g., a specific HTTP server version), a hyperedge is created linking them all.
*   **Subnet Groups:** Similarly, `create_subnet_hyperedges` automatically links devices within the same CIDR block.

### 4. Integration with the Ecosystem

The server is designed to be a good citizen within the larger NerfEngine architecture:
*   **Event Bus:** It publishes `NODE_CREATE` and `HYPEREDGE_CREATE` events, allowing other subsystems (like the AI signal classifier) to react to new data.
*   **Hypergraph Engine Mirroring:** Data is automatically mirrored into a unified `HypergraphEngine`, ensuring that the visualization layer and the analytical layer are always in sync.

## Under the Hood

The server is built on a robust Python stack:
*   **Flask:** Lightweight web framework for the REST API.
*   **Flask-SocketIO:** For low-latency data streaming.
*   **Nmap:** Direct subprocess integration for active scanning.
*   **Numpy/Scipy:** For heavy numerical lifting and spatial calculations.

## Conclusion

The RF Scythe API Server represents a shift in how we think about signal intelligence. By moving away from isolated lists of frequencies or IP addresses and towards a connected **Hypergraph**, we gain the ability to see the hidden structures that define the modern electromagnetic and digital landscape.

Whether you're tracking interference patterns or mapping a local network, RF Scythe provides the structural backbone to turn raw data into actionable intelligence.

---
*For more technical details, check the source code in `NerfEngine/rf_scythe_api_server.py`.*